.\"Copyright 2010-2020 Red Hat, Inc. and/or its affiliates.
.\"
.\"Licensed to you under the GNU General Public License as published by
.\"the Free Software Foundation; either version 2 of the License, or
.\"(at your option) any later version.  See the files README and
.\"COPYING which accompany this distribution.
.\"
.\"
.\" File Name macro definition plagiarized from bash.
.\"
.de FN
\fI\|\\$1\|\fP
..
.TH VDSMD 8 "January 1, 2012" "" ""
.SH NAME
vdsmd \- Virtual Desktops and Servers Manager
.br
@ENGINENAME@ host agent
.SH SYNOPSIS
.BR "service vdsmd start"
.SH DESCRIPTION
The
.B VDSM
service is required by a
.B @ENGINENAME@
to manage oVirt Nodes
and Linux hosts. Currently, only Fedora and Red Hat Enterprise Linux
are supported. VDSM manages and monitors the host's
storage, memory and networks as well as virtual machine creation, other host
administration tasks, statistics gathering, and log collection.

VDSM should be run as a daemon on each node managed by @ENGINENAME@.
It answers XML-RPC calls from clients (mostly @ENGINENAME@).

.SH HOOKS
VDSM is extendible: it has hooks in strategic locations, where it executes
external scripts.
.B
Hooks API is new and is subject to future changes.
Currently-supported hooks have self-explanatory names:
    before_vm_start, after_vm_start,
    before_vm_cont, after_vm_cont,
    before_vm_pause, after_vm_pause,
    before_vm_hibernate, after_vm_hibernate,
    before_vm_dehibernate, after_vm_dehibernate,
    before_vm_migrate_source, after_vm_migrate_source,
    before_vm_migrate_destination, after_vm_migrate_destination,
    before_device_migrate_source, after_device_migrate_source,
    before_device_migrate_destination, after_device_migrate_destination,
    before_vm_destroy, after_vm_destroy,
    before_vm_set_ticket, after_vm_set_ticket,
    before_device_create, after_device_create,
    before_device_destroy, after_device_destroy,
    before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,
    before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,
    before_update_device, after_update_device, after_update_device_fail,
    after_disk_prepare,
    before_disk_hotplug, after_disk_hotplug,
    before_disk_hotunplug, after_disk_hotunplug,
    before_vdsm_start, after_vdsm_stop,
    before_network_setup, after_network_setup, after_network_setup_fail,
    before_set_num_of_cpus, after_set_num_of_cpus,
    before_get_vm_stats, after_get_vm_stats,
    before_get_all_vm_stats, after_get_all_vm_stats,
    before_get_caps, after_get_caps,
    before_get_stats, after_get_stats,
    after_hostdev_list_by_caps,
    before_memory_hotplug, after_memory_hotplug.

Each hook executes the scripts under
.FN /usr/libexec/vdsm/hooks/<hook-name>/
in lexicographic order.

.SS Hook environment
Each hook script (except before_vdsm_start, after_vdsm_stop,
before_network_setup, after_network_setup and after_network_setup_fail,
before_get_vm_stats, after_get_vm_stats,
before_get_all_vm_stats, after_get_all_vm_stats,
before_get_caps, after_get_caps,
before_get_stats, after_get_stats, after_hostdev_list_by_caps) inherit
the environment of the VDSM process, with an additional variable
.B _hook_domxml
which holds the path of libvirt's
.B domain xml
representation of the relevant virtual machine.
The uuid of the virtual machine may be deduced from that xml, but it is also
available as the environment variable
.B vmId.

The before_network_setup, after_network_setup and after_network_setup_fail
hooks do also include an extra environment variable
.B _hook_json
which holds a pointer to a file with the network parameters that vdsm is
setting up (
.B request
)
, the request may be modified by the before_network_setup hook as thus affect
the operation ultimately taken place by Vdsm.

The JSON format of this file for before_network_setup, after_network_setup and
after_network_setup_fail has one section: request, this section
contains networks, bondings and options, those parameters are specified
in the setupNetworks VDSM API call.

.nf
{"request":
    {
    "networks": {"virtnet": {"bonding" : "bond0", "bridged": true, "vlan":27}},
    "bondings": {"bond0": {"nics":["eth1","eth2"]}},
    "options":  {"conectivityCheck":false}
    }
 }
.fi

The after_disk_prepare hook is invoked after a disk is prepared during VM
create, resume, recovery and incoming migration flows.
.B Warning:
In incoming migration flow, the hook should finish quickly to avoid migration
timeout.

The after_disk_prepare hook includes only a
.B _hook_json
key with a filename where the disk info is stored in JSON format:

.nf
{
    "disk": {
        "diskType": "file",
        "device": "disk",
        "domainID": "uuid",
        "format": "cow",
        "imageID": "uuid",
        "path": "/path/to/disk",
        "volumeID": "uuid"
        ...
    }
}
.fi

See the VmDiskDevice type in vdsm schema for the complete contents of
the disk info dict.

If the after_disk_prepare hook modify the disk, vdsm will use the modified disk
instead of the original disk. See vdsm_hooks/localdisk for example for
converting a shared disk of any type to a local block device.

Hooks that handle NIC hotplug, hotunplug and update device
have the _hook_domxml variable but it contains the representation of the NIC
rather than the VM. Hotplug/hotunplug disk hooks also have the _hook_dom_xml variable,
which contains the drive definition (not the VM).
All hook points that are device specific get the xml of the device
instead of the entire VM. Such hooks are listed below.

On top of these, @ENGINENAME@ allows to set a collection of "custom parameters" for
each virtual machine.  Each of these parameters is provided to hooks as an
environment variable.

before_migration_destination (and before_dehibernation) hooks currently receive
the xml of the domain from the source host. The xml of the domain at the
destination will differ in various details.

The environment of before_vm_set_ticket and after_vm_set_ticket hooks is augmented
with a set of params passed by the caller of setVmTicket.

The environment of before_vm_dehibernate and after_vm_dehibernate hooks have
FROM_SNAPSHOT variable set to True if the VM is being restored from a live snapshot.

The environment of hooks specific to devices:
    before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,
    before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,
    before_update_device, after_update_device, after_update_device_fail,
    before_disk_hotplug, after_disk_hotplug,
    before_disk_hotunplug, after_disk_hotunplug,
    before_device_create, after_device_create,
    before_device_destroy, after_device_destroy,
    before_device_migrate_source, after_device_migrate_source,
    before_device_migrate_destination, after_device_migrate_destination,
    before_memory_hotplug, after_memory_hotplug.

Are all augmented by custom properties specific to those devices,
sent by the caller of the hook. For example if before_nic_hotplug is called
with custom: {qos: '0.5', color: 'red'} then qos and color will be directly
available as environment variables when before_nic_hotplug is called.

before_get_vm_stats and before_get_all_vm_stats are called upon API request to
get VM statistics, before getVmStats and getAllVmStats respectively. Those hooks
do not receive any parameters.

after_get_vm_stats and after_get_all_vm_stats are called upon getVmStats and
getAllVmStats respectively. Both receive a parameter in _hook_json containing
a list of dictionaries of VM stats (in case of
after_get_vm_stats the list will have a single element):
.nf
[
	{"vm_id": "...", ... },
	{"vm_id": "...", ... },
	...
]
.fi

before_get_caps and after_get_caps are called before (and after)
a getVdsCapabilities API request.
after_get_caps receives the complete capabilities dictionary within _hook_json.

before_get_stats and after_get_stats are called before (and after)
a getVdsStats API request.
after_get_stats receives the complete host statistics dictionary within
_hook_json.

.SS Hook execution
before_vdsm_start script is executed as user
.I root.
All the other hooks are executed as user
.I vdsm.

.B before_vm_start
scripts may edit the domain xml file (pointed by
.B _hook_domxml
) in order to change VDSM's definition of a
virtual machine before it reaches libvirt. As with all hooks, the China Store
Rule applies - if you break something, you own it. Any script can mess up
VDSM's operation badly. In particular, you may never change the uuid of the
domain, and should better know what you are doing if you remove a device from
the domain.

before_vm_start and before_device_create may alter the vm start behavior by
modifying the vm libvirt vm startup flags. The flag must be written to the
@VDSMRUNDIR@/hook/<vm id>/launchflags file, the required value being a decimal
based on the libvirt virDomainCreateFlags enum values.

Standard error of hook scripts is collected into VDSM's log, which may be used
by scripts for debugging.

As a somewhat silly example, let us think of a script that warns when a
domain with too much memory is started on a host:

.nf
    #!/bin/bash

    mem=\`/usr/bin/xpath $_hook_domxml '/domain/memory/text()' 2> /dev/null\`

    if [ "$mem" -gt 1073741824 ]; then
        echo "Domain with more than Gb!" >&2
    fi

    exit 0
.fi

.SS Hook return code
Hook script must return one of the following return codes:

.PD 0
.TP
.B
0
the hook script ended successfully.
.TP
.B
1
the hook script failed, other hooks should be processed.
.TP
.B
2
the hook script failed, no further hooks should be processed.
.TP
.B
>2
reserved.

.TP
If a before_<action> hook fails, the <action> would be aborted.
However, before_vm_destroy's failure does not abort destroy().

.SH FILES
.PD 0
.TP
.FN /etc/vdsm/vdsm.conf
VDSM main configuration file. Use with great caution; some information about available variables and their meaning appear in
.FN /usr/share/doc/vdsm-<version>/vdsm.conf.sample
.TP
.FN /var/log/vdsm/vdsm.log
Default log location for vdsm.
.TP
.FN /usr/share/doc/vdsm-<version>/vdsm-api.html
vdsm QAPI documentation.
.TP
.FN /etc/pki/vdsm
VDSM's trust store: server key, certificate, and @ENGINENAME@ CA's certificate.
.TP
.FN @VDSMREPO@
VDSM's image repository, or more exactly, links to NFS exports and iSCSI or
FiberChannel devices which VDSM uses.


.SH SEE ALSO
.BR vdsm-client(1)
.br
.BR https://www.ovirt.org/develop/developer-guide/vdsm/vdsm/
.br
.BR https://github.com/oVirt/vdsm
.br
.BR https://travis-ci.org/oVirt/vdsm

.SH AUTHOR
VDSM was written by Ayal Baron, Barak Azulay, Cyril Plisko, Dan Kenigsberg,
Doron Fediuck, Igor Lvovsky, Saggi Mizrahi, Shahar Frank, Simon Grinberg, and
probably others.

.SH BUGS
Report bugs to <http://bugzilla.redhat.com>

.SH COPYRIGHT
Copyright 2010-2017 Red Hat, Inc. License GPLv2: GNU GPL Version 2 <http://gnu.org/licenses/gpl.html>.
